Contours and Contour Direction (IM: XG)

Inside Macintosh: QuickDraw GX Graphics /: Chapter 4 - Geometric Operations / About Geometric Operations

Contours and Contour Direction
With the exception of empty, full, and point shapes, geometric shapes are made up of contours. Line, curve, and rectangle shapes have a single contour, while polygon and path shapes can have zero, one, or more contours. Every contour is defined by an ordered series of on-curve or off-curve geometric points, or a combination of both.
For example, the geometry of a line shape contains two (on-curve) geometric points--a first point and a last point. The contour of a line shape is the line segment connecting these two points. Since the line has a first point and a last point, it also has a direction, a right side, and a left side, as shown in Figure 4-1.
Figure 4-1 Line contours

As another example, a path shape can have multiple contours; each path contour is defined by a series of on-curve and off-curve points. As with line contours, each path contour has a direction, a right side, and a left side. Notice that the order of the geometric points decides which side is the left side and which side is the right side, as shown in Figure 4-2.
Figure 4-2 A path shape with two contours

Each contour of a polygon or path shape has an implied line (or curve) connecting the last geometric point of the contour to the first geometric point of the contour. QuickDraw GX uses this implied line (or curve) when the shape fill of the polygon or path shape is the closed-frame shape fill or any of the solid shape fills. These implied lines are shown in gray in Figure 4-2.
Notice that the right side of the first contour falls inside the area enclosed by the contour and the right side of the second contour falls outside the area enclosed by the contour.
All contours have either a clockwise or a counterclockwise contour direction. Sometimes the contour direction of a contour is obvious, such as the contour directions of the contours in Figure 4-2. In this figure, the first contour has a clockwise contour direction and the second contour has a counterclockwise contour direction. However, sometimes the contour direction is not so obvious. Figure 4-3 gives an example.
Figure 4-3 A path whose contour direction is not immediately obvious

The upper half of the contour shown in Figure 4-3 seems to have a counterclockwise direction while the lower half of the contour seems to have a clockwise direction. In cases like this one, QuickDraw GX assigns an arbitrary contour direction to the entire contour. You can use the GXGetShapeDirection function, described on page 4-68, to find the contour direction that QuickDraw GX has assigned to a particular contour.
QuickDraw GX uses contour direction for a number of purposes--for example, when filling shapes that have a winding shape fill. The path shape shown in Figure 4-4 contains an inner contour with the same contour direction as the contour that surrounds it. When drawing this path using a winding fill, QuickDraw GX ignores the inner contour.
Figure 4-4 A path whose inner contour has the same contour direction as its outer contour

To indicate that QuickDraw GX should not ignore the inner contour, you could change the shape fill to even-odd fill, or you could reverse the contour direction of the inner contour, as shown in Figure 4-5.
Figure 4-5 A path shape whose inner and outer contours have different contour directions

QuickDraw GX lets you reverse a contour's direction by reversing the order of the geometric points in the contour.

Note
QuickDraw GX always considers line shapes to have a clockwise contour direction, regardless of the order of the geometric points in the line's geometry. Therefore, you cannot change the contour direction of line shapes. However, a line contour in a polygon or a path does have a clockwise or a counterclockwise direction (which QuickDraw GX assigns to it depending on the other contours in the shape); therefore, you can change the contour direction of line contours in polygons and paths.
In certain situations, QuickDraw GX needs to know which side of a contour is the inside and which is the outside--for example, when drawing a geometric shape that has the inside-frame style attribute set. The default assumption is that the right side of a contour is the inside--which works well for clockwise contours but can produce surprising results with counterclockwise contours. The auto-inset style attribute indicates that QuickDraw GX should find the true inside for each contour of a shape, rather than assuming the right side is the inside. The true inside of a contour is defined to be the right side of the contour if the contour direction is clockwise and the left side of a contour if the contour direction is counterclockwise.
You can find more information about the inside-frame style attribute and the auto-inset style attribute in Chapter 3, "Geometric Styles," in this book.
The section "Determining and Reversing Contour Direction" beginning on page 4-23 contains programming examples relating to contour direction.